
               RiscOS Solitaire and Colotaire

         Version 7.18,     dated 21st November, 2002
                   by R.I.D.Macfarlane

This application demonstrates how a traditional board game
can be transferred into the RiscOS multitasking WIMP
system.  The author has used the application as a vehicle
to explore this system and unique routines for sprite, menu
and incarnation handling are included together with a drag
mechanism featuring pointer/sprite exchange.

A control window allows the various options to be easily
setup and a second passive window can display a quarter
scale snapshot of the window containing the game. The
sprites, backdrop, control window sprites and template can
all be altered to customise the display. Optionally a random
function will produce a different veneer at each startup.

The program will multi-task with itself or others.  Each
incarnation is given a different ball colour. There are
various help files, which are selected from the control
window and are available in either HTML or text form.

The HelpPlay file which is available in this folder gives
instructions for playing, options and application messages.

The HelpText file provides messages for ACORN's Interactive
Help application as well as error messages and menu items.

The Soli_Help and Colo_Help files provide a summary of the
rules of the games and how to play them.



INTERNATIONAL LANGUAGES

All text including menu items may be displayed in any
foreign language that is supported by the system's
international module.

All text files are to be found in folders named as the
country whose language they are written in.  Any text files
that are missing from a folder will be loaded in from the
default (English) folder.

If you wish to create another folder, use the same name for
the directory as given by the *Country command.  The text
files are in free format, except "HelpText".  This file
comprises strings of text that are separated by the code
&0d, Return and incrementing line numbers.  The program
finds the right string by counting down the number of
'Return' codes and checking against the embedded line
numbers, so that it is important that these are all
retained in the correct positions.

The two characters "|M" can be used to start newlines
within a string of text for display by the Interactive
Application.  However only the first part will be displayed
in the error message box.  Note that there are only four
lines of text which are displayed by the application.

Use the !Edit application; at the start, choose the CR<->LF
option in the edit submenu to make the job easier, but
remember to reset this option at the end of the edit,
before saving the file.



CUSTOMISING THE DISPLAY

The Veneers folder contains several directories, who names
are used to specify the veneer type. There is a system
variable which may be specified in the !Run file to point at
the required veneer to be used on startup. This variable may
take the value 'Random' in which case different veneers will
be used for each startup.

Each veneer directory may comprise the following file names
and if any are missing then the default files will be used:-

 Choices:    a text file holding the veneer's parameters
 Sprites:    a sprite file holding ALL the alternative sprites
 Background: a sprite file holding the tile_1 sprite + others
 Templates:  a template file defining the control window
 CtlSprites: a sprite file for alternative radio & option icons

There is a degree of flexibility with the size and shapes of
the sprites allowed.  The size of the sprite used for the
hole (numbered 7) determines the framework and size of the
working area.   

If the alternative radio & option icons are to be found in
the Background file rather than in 'their own' CtlSprites
file, then the background sprite will be used for both the
play and control windows [eg. the Yellow veneer]

Some icons are missing intentionally from being shown but
must be retained in the template in order to keep the icon
numbering correct [they are hiding from view and therefore
cannot be selected, eg the Crail and Yellow veneers].  In
this case the values supplied by the respective Choices file
will be used for the missing functions.
 


APPLICATION ENVIRONMENT

The application is RiscOS compatible.  If the monitor in
use is monochrome, it is suggested that a two colour mode
is chosen for display, since it is otherwise difficult to
distinguish colours in the Colotaire game.  Special sprites
have been constructed for the 2 colour modes and will be
loaded automatically.

A Large Format veneers folder has been added for the benefit
of those with an Iyonix or the Viewfinder system extension.
This folder is automatically selected when the number of
screen pixels exceeds 1500 in the x direction.  This can
also be effected with a RiscPC with 2Mb VRAM by selecting
the screen size 1600 x 600 in either 256 or 32k colours.

The original program was designed to use the ColourTrans
module in order to plot scaled sprites and change the
pointer to a ball during a drag function.  This is no longer
supported by versions of the program greater than 7.00. 
However deep coloured sprites (16M and 32k colours) can be
used for the balls, etc and can be dragged around the screen
as expected. This does restrict the application to working
in a RiscOS system with a version number equal to or greater
than 3.60.  Use Solitaire version 5.13 if this is a problem.

The modules, 'HOLED' and 'BELL', written by Gordon J. Key,
from the excellent golf program 'HoledOut' [ Published by
the 4th Dimension ] have been added to the application's
directory to provide interesting sound effects.  These are
supplied with the permission of the owner of the copyright,
to whom the author expresses his thanks. These have been
converted to 26 / 32 bit neutral for use with Risc OS
version 5.

The default sound voice 'StringLib-Hard' is used to
indicate user errors.  If absent, the current bell voice
will be used.

The application attempts to make the sound facilities
multi-user friendly, by removing channel assignments and
voices at the end of use.  The sound menu selection will
also attempt to reload any voices and reselect any channels
that may have become deselected by other applications.



VERSION HISTORY

1.00   12-Jul-1990
2.00   21-Oct-1990  Second passive, quarterscale window
3.00   27-Dec-1990  Sound functions added.
4.00    7-Jan-1991  Standard routines to library.
5.00   07-Apr-1991  International text release
5.12   20-Apr-1995  Country error [RiscOS 3+] fixed
                    Error reporting for RiscOS 3.5+
5.13   18-Dec-2000  Playback error corrected.  Drop back
                    in same hole for Ghost/Blind corrected
                    !Sprites22 file added
7.16   15-Jan-2001  Control dialogue window
                    Customising veneers added
7.18   21-Nov-2002  RISC OS 5 compatibility



SOFTWARE OWNERSHIP  &  TERMS OF USE

With the exception of the modules 'HOLED' & 'BELL'
mentioned above, the application has been written solely by
the author, R.I.D.Macfarlane, who retains copyright, whilst
the material is in the Public Domain.  This means that you
can copy the application and its files, but no part of it
can be copied for commercial purposes or charged for or
included on a disk for which a charge is being made.  The
application must not be changed, with the exception of the
!Boot and !Run files and additions to the Veneer and Text
folders.

This readme file must always accompany the application.
The application must not be uploaded to a bulletin board.
These copying rights may be withdrawn if they are found to
be being misused.



CONTACT Ian Macfarlane at:-

  ian@maceng.karoo.co.uk

the web-site is at:-

  http://www.maceng.karoo.net/BG/solitaire.html

or more briefly:-

 http://Solitaire.riscos.org.uk
